<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=2">
<meta name="theme-color" content="#222">
<meta name="generator" content="Hexo 4.2.1">
  <link rel="apple-touch-icon" sizes="180x180" href="/images/apple-touch-icon.png">
  <link rel="icon" type="image/png" sizes="32x32" href="/images/favicon-32x32.png">
  <link rel="icon" type="image/png" sizes="16x16" href="/images/favicon-16x16.png">
  <link rel="mask-icon" href="/images/logo.svg" color="#222">

<link rel="stylesheet" href="/css/main.css">


<link rel="stylesheet" href="/lib/font-awesome/css/all.min.css">

<script id="hexo-configurations">
    var NexT = window.NexT || {};
    var CONFIG = {"hostname":"www.lixiaofei.cn","root":"/","scheme":"Mist","version":"7.8.0","exturl":false,"sidebar":{"position":"left","display":"post","padding":18,"offset":12,"onmobile":false},"copycode":{"enable":false,"show_result":false,"style":null},"back2top":{"enable":true,"sidebar":false,"scrollpercent":false},"bookmark":{"enable":false,"color":"#222","save":"auto"},"fancybox":false,"mediumzoom":false,"lazyload":false,"pangu":false,"comments":{"style":"tabs","active":true,"storage":true,"lazyload":true,"nav":{"valine":{"order":-1}}},"algolia":{"hits":{"per_page":10},"labels":{"input_placeholder":"Search for Posts","hits_empty":"We didn't find any results for the search: ${query}","hits_stats":"${hits} results found in ${time} ms"}},"localsearch":{"enable":false,"trigger":"auto","top_n_per_article":1,"unescape":false,"preload":false},"motion":{"enable":true,"async":false,"transition":{"post_block":"fadeIn","post_header":"slideDownIn","post_body":"slideDownIn","coll_header":"slideLeftIn","sidebar":"slideUpIn"}}};
  </script>

  <meta name="description" content="文档的重要性无容置疑，而且文档编写能力是程序员最重要的软实力之一。不过编写文档不仅枯燥，而且后期制作难度高，谁都不愿意做。 今天我们来聊一聊，如何利用 markdown 高效地编写阅读方便结构完整，甚至支持关键字搜索的 Web 文档吧，让写文档上瘾。开干！">
<meta property="og:type" content="article">
<meta property="og:title" content="不会写文档，叫什么高级程序员">
<meta property="og:url" content="http://www.lixiaofei.cn/2021-07-10-readthedocs/index.html">
<meta property="og:site_name" content="管窥程序">
<meta property="og:description" content="文档的重要性无容置疑，而且文档编写能力是程序员最重要的软实力之一。不过编写文档不仅枯燥，而且后期制作难度高，谁都不愿意做。 今天我们来聊一聊，如何利用 markdown 高效地编写阅读方便结构完整，甚至支持关键字搜索的 Web 文档吧，让写文档上瘾。开干！">
<meta property="og:locale" content="zh_CN">
<meta property="og:image" content="http://www.lixiaofei.cn/images/2021/07/readthedocs/00.jpg">
<meta property="og:image" content="http://www.lixiaofei.cn/images/2021/07/readthedocs/01.png">
<meta property="og:image" content="http://www.lixiaofei.cn/images/2021/07/readthedocs/03.png">
<meta property="og:image" content="http://www.lixiaofei.cn/images/2021/07/readthedocs/02.png">
<meta property="og:image" content="http://www.lixiaofei.cn/images/2021/07/readthedocs/04.png">
<meta property="article:published_time" content="2021-07-09T16:00:00.000Z">
<meta property="article:modified_time" content="2021-08-19T04:19:56.474Z">
<meta property="article:author" content="太阳雪">
<meta property="article:tag" content="编程">
<meta property="article:tag" content="游戏">
<meta property="article:tag" content="Pygame">
<meta name="twitter:card" content="summary">
<meta name="twitter:image" content="http://www.lixiaofei.cn/images/2021/07/readthedocs/00.jpg">

<link rel="canonical" href="http://www.lixiaofei.cn/2021-07-10-readthedocs/">


<script id="page-configurations">
  // https://hexo.io/docs/variables.html
  CONFIG.page = {
    sidebar: "",
    isHome : false,
    isPost : true,
    lang   : 'zh-CN'
  };
</script>

  <title>不会写文档，叫什么高级程序员 | 管窥程序</title>
  






  <noscript>
  <style>
  .use-motion .brand,
  .use-motion .menu-item,
  .sidebar-inner,
  .use-motion .post-block,
  .use-motion .pagination,
  .use-motion .comments,
  .use-motion .post-header,
  .use-motion .post-body,
  .use-motion .collection-header { opacity: initial; }

  .use-motion .site-title,
  .use-motion .site-subtitle {
    opacity: initial;
    top: initial;
  }

  .use-motion .logo-line-before i { left: initial; }
  .use-motion .logo-line-after i { right: initial; }
  </style>
</noscript>

</head>

<body itemscope itemtype="http://schema.org/WebPage">
  <div class="container use-motion">
    <div class="headband"></div>

    <header class="header" itemscope itemtype="http://schema.org/WPHeader">
      <div class="header-inner"><div class="site-brand-container">
  <div class="site-nav-toggle">
    <div class="toggle" aria-label="切换导航栏">
      <span class="toggle-line toggle-line-first"></span>
      <span class="toggle-line toggle-line-middle"></span>
      <span class="toggle-line toggle-line-last"></span>
    </div>
  </div>

  <div class="site-meta">

    <a href="/" class="brand" rel="start">
      <span class="logo-line-before"><i></i></span>
      <h1 class="site-title">管窥程序</h1>
      <span class="logo-line-after"><i></i></span>
    </a>
      <p class="site-subtitle" itemprop="description">Today is a gift</p>
  </div>

  <div class="site-nav-right">
    <div class="toggle popup-trigger">
    </div>
  </div>
</div>




<nav class="site-nav">
  <ul id="menu" class="main-menu menu">
        <li class="menu-item menu-item-home">

    <a href="/" rel="section"><i class="fa fa-home fa-fw"></i>首页</a>

  </li>
        <li class="menu-item menu-item-about">

    <a href="/about/" rel="section"><i class="fa fa-user fa-fw"></i>关于</a>

  </li>
        <li class="menu-item menu-item-tags">

    <a href="/tags/" rel="section"><i class="fa fa-tags fa-fw"></i>标签</a>

  </li>
        <li class="menu-item menu-item-categories">

    <a href="/categories/" rel="section"><i class="fa fa-th fa-fw"></i>分类</a>

  </li>
        <li class="menu-item menu-item-archives">

    <a href="/archives/" rel="section"><i class="fa fa-archive fa-fw"></i>归档</a>

  </li>
  </ul>
</nav>




</div>
    </header>

    
  <div class="back-to-top">
    <i class="fa fa-arrow-up"></i>
    <span>0%</span>
  </div>
  <div class="reading-progress-bar"></div>

  <a href="https://github.com/alisx" class="github-corner" title="Follow me on GitHub" aria-label="Follow me on GitHub" rel="noopener" target="_blank"><svg width="80" height="80" viewBox="0 0 250 250" aria-hidden="true"><path d="M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z"></path><path d="M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2" fill="currentColor" style="transform-origin: 130px 106px;" class="octo-arm"></path><path d="M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.7,120.9 152.7,124.9 L141.0,136.5 C139.8,137.7 141.6,141.9 141.8,141.8 Z" fill="currentColor" class="octo-body"></path></svg></a>


    <main class="main">
      <div class="main-inner">
        <div class="content-wrap">
          

          <div class="content post posts-expand">
            

    
  
  
  <article itemscope itemtype="http://schema.org/Article" class="post-block" lang="zh-CN">
    <link itemprop="mainEntityOfPage" href="http://www.lixiaofei.cn/2021-07-10-readthedocs/">

    <span hidden itemprop="author" itemscope itemtype="http://schema.org/Person">
      <meta itemprop="image" content="/images/avatar.png">
      <meta itemprop="name" content="太阳雪">
      <meta itemprop="description" content="总结 技术 思考 想法">
    </span>

    <span hidden itemprop="publisher" itemscope itemtype="http://schema.org/Organization">
      <meta itemprop="name" content="管窥程序">
    </span>
      <header class="post-header">
        <h1 class="post-title" itemprop="name headline">
          不会写文档，叫什么高级程序员
        </h1>

        <div class="post-meta">
            <span class="post-meta-item">
              <span class="post-meta-item-icon">
                <i class="far fa-calendar"></i>
              </span>
              <span class="post-meta-item-text">发表于</span>

              <time title="创建时间：2021-07-10 00:00:00" itemprop="dateCreated datePublished" datetime="2021-07-10T00:00:00+08:00">2021-07-10</time>
            </span>
              <span class="post-meta-item">
                <span class="post-meta-item-icon">
                  <i class="far fa-calendar-check"></i>
                </span>
                <span class="post-meta-item-text">更新于</span>
                <time title="修改时间：2021-08-19 12:19:56" itemprop="dateModified" datetime="2021-08-19T12:19:56+08:00">2021-08-19</time>
              </span>

          
            <span id="/2021-07-10-readthedocs/" class="post-meta-item leancloud_visitors" data-flag-title="不会写文档，叫什么高级程序员" title="阅读次数">
              <span class="post-meta-item-icon">
                <i class="fa fa-eye"></i>
              </span>
              <span class="post-meta-item-text">阅读次数：</span>
              <span class="leancloud-visitors-count"></span>
            </span>
  
  <span class="post-meta-item">
    
      <span class="post-meta-item-icon">
        <i class="far fa-comment"></i>
      </span>
      <span class="post-meta-item-text">Valine：</span>
    
    <a title="valine" href="/2021-07-10-readthedocs/#valine-comments" itemprop="discussionUrl">
      <span class="post-comments-count valine-comment-count" data-xid="/2021-07-10-readthedocs/" itemprop="commentCount"></span>
    </a>
  </span>
  
  

        </div>
      </header>

    
    
    
    <div class="post-body" itemprop="articleBody">

      
        <p><img src="../images/2021/07/readthedocs/00.jpg" alt="标题图"></p>
<p>文档的重要性无容置疑，而且文档编写能力是程序员最重要的软实力之一。不过编写文档不仅枯燥，而且后期制作难度高，谁都不愿意做。</p>
<p>今天我们来聊一聊，如何利用 <a href="https://markdown.com.cn/basic-syntax/" target="_blank" rel="noopener" title="markdown">markdown</a> 高效地编写阅读方便结构完整，甚至支持关键字搜索的 Web 文档吧，让写文档上瘾。开干！</p>
<a id="more"></a>
<h2 id="文档框架">文档框架</h2>
<p>同博客框架 <a href="https://cn.wordpress.org/" target="_blank" rel="noopener" title="WordPress">WordPress</a>、<a href="https://hexo.io/zh-cn/index.html" target="_blank" rel="noopener" title="Hexo">Hexo</a> 等一样，Web 文档也有自己的框架，如比如 Java 的 <a href="https://en.wikipedia.org/wiki/Javadoc" target="_blank" rel="noopener" title="Javadoc">Javadoc</a>，Python 的 <a href="https://docs.python.org/3/library/pydoc.html" target="_blank" rel="noopener" title="pydoc">pydoc</a>，以及<a href="https://www.sphinx-doc.org/en/master/usage/quickstart.html" target="_blank" rel="noopener" title="Python-sphinx">Python-sphinx</a></p>
<p>对于 Python 有专门文档标记语言 <a href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html" target="_blank" rel="noopener" title="reStructuredText（RST）">reStructuredText（RST）</a>，常见的 Python 各种库和工具的帮助文档基本都是用 RST 所写。</p>
<p>如 <a href="https://docs.python-requests.org/zh_CN/latest/" target="_blank" rel="noopener" title="Requests">Requests</a>、<a href="https://flask.palletsprojects.com/en/2.0.x/" target="_blank" rel="noopener" title="Flask">Flask</a>、<a href="https://docs.scrapy.org/en/latest/" target="_blank" rel="noopener" title="Scrapy">Scrapy</a> 等。</p>
<p>例如 <code>Scrapy</code> 的文档</p>
<p><img src="../images/2021/07/readthedocs/01.png" alt="截图Scrapy的文档"></p>
<p>不过，用 RST 编写对于已经会了 Markdown（更为流行） 的读者来说，有点浪费，而且两者的语法差异较大，容易造成记忆冲突。</p>
<p>幸运的是有了 <a href="https://www.mkdocs.org/" target="_blank" rel="noopener" title="mkdocs">mkdocs</a>，不仅能轻松制作类似 Scrapy 帮助文档的文档项目，而且支持 markdown 语法。</p>
<h2 id="Mkdocs">Mkdocs</h2>
<p>MkDocs 是一个快速、简单、可以效果惊艳的采用 Markdown 语法编写的静态站点生成器，主要用于构建项目文档。</p>
<h3 id="环境搭建">环境搭建</h3>
<p>安装了 Python，有了 pip，运行以下命令就可以安装 MkDocs 了：</p>
<figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">pip install mkdocs</span><br></pre></td></tr></table></figure>
<p>查看 MkDocs 版本：</p>
<figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line">mkdocs --version</span><br><span class="line"></span><br><span class="line">mkdocs, version 1.2.1 from &lt;...&gt;\lib\site-packages\mkdocs (Python 3.9)</span><br></pre></td></tr></table></figure>
<p>如上，即 MkDocs 安装正常了。</p>
<h3 id="创建项目">创建项目</h3>
<p>就可以用 MkDocs 创建一个文档项目了。</p>
<p>命令行进入需要创建文档项目的目录，然后执行：</p>
<figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">mkdocs new testdocs</span><br></pre></td></tr></table></figure>
<p>这样就在当前目录下，生成了一个 testdocs 文件夹，就是创建的文档项目。</p>
<p>项目目录结构如下：</p>
<p><img src="../images/2021/07/readthedocs/03.png" alt="项目目录结构"></p>
<p>mkdocs.yml 为配置文件</p>
<p>docs 文件夹中为文档文件目录，文件使用 markdown 编写。</p>
<h3 id="文档预览">文档预览</h3>
<p>进入 testdocs 目录（也就是创建的文档项目目录，你的可能不同），执行 <code>mkdocs serve</code>：</p>
<figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br></pre></td><td class="code"><pre><span class="line">mkdocs serve</span><br><span class="line"></span><br><span class="line">INFO     -  Building documentation...</span><br><span class="line">INFO     -  Cleaning site directory</span><br><span class="line">INFO     -  Documentation built <span class="keyword">in</span> 0.16 seconds</span><br><span class="line">INFO     -  [18:16:18] Serving on http://127.0.0.1:8000/</span><br></pre></td></tr></table></figure>
<p>将启动一个 Web 服务器，用于预览 testdocs 文件项目，效果如下：</p>
<p><img src="../images/2021/07/readthedocs/02.png" alt="文档预览"></p>
<p>很惊艳吧，而且支持多种站点分格。</p>
<p>文档预览会在文档发生变化时自动刷新，可以随时看到最新效果。</p>
<h2 id="编写文档">编写文档</h2>
<p>搭建好了项目，就可以开始编写文档了，总体和写这篇文章差不多。</p>
<h3 id="配置">配置</h3>
<p>mkdocs 的配置简单明了，采用 yml 格式：</p>
<figure class="highlight yml"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br></pre></td><td class="code"><pre><span class="line"><span class="attr">site_name:</span> <span class="string">MkLorum</span></span><br><span class="line"><span class="attr">site_url:</span> <span class="string">https://example.com/</span></span><br><span class="line"><span class="attr">nav:</span></span><br><span class="line">    <span class="bullet">-</span> <span class="attr">Home:</span> <span class="string">'index.md'</span></span><br><span class="line">    <span class="bullet">-</span> <span class="attr">About:</span> <span class="string">'markdown.md'</span></span><br><span class="line"><span class="attr">theme:</span> <span class="string">readthedocs</span></span><br></pre></td></tr></table></figure>
<p>需要注意的是 nav 配置，当文档比较复杂时，可以通过嵌套的方式。</p>
<p>例如在 Home 下还有子菜单，menu1 和 menu2，可以配置成：</p>
<figure class="highlight yml"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br></pre></td><td class="code"><pre><span class="line"><span class="attr">nav:</span></span><br><span class="line">    <span class="bullet">-</span> <span class="attr">Home:</span> <span class="string">'index.md'</span></span><br><span class="line">    <span class="bullet">-</span> <span class="attr">'User Guide':</span></span><br><span class="line">        <span class="bullet">-</span> <span class="attr">'Writing your docs':</span></span><br><span class="line">            <span class="bullet">-</span> <span class="attr">Menu1 :</span> <span class="string">'menu1.md'</span></span><br><span class="line">            <span class="bullet">-</span> <span class="attr">Menu2 :</span> <span class="string">'menu2.md'</span></span><br><span class="line">        <span class="bullet">-</span> <span class="attr">'Styling your docs':</span> <span class="string">'./style/styling-your-docs.md'</span></span><br><span class="line">    <span class="bullet">-</span> <span class="attr">About:</span></span><br><span class="line">        <span class="bullet">-</span> <span class="attr">'License':</span> <span class="string">'license.md'</span></span><br><span class="line">        <span class="bullet">-</span> <span class="attr">'Release Notes':</span> <span class="string">'release-notes.md'</span></span><br></pre></td></tr></table></figure>
<p>效果如下：</p>
<p><img src="../images/2021/07/readthedocs/04.png" alt="导航"></p>
<ul>
<li>如果菜单名中有空格需要用引号(单双皆可)括起来</li>
<li>文档文件不要同导航结构配合，可以为导航配置相对文件路径</li>
<li>菜单层级可以无限嵌套</li>
</ul>
<h3 id="一些约定">一些约定</h3>
<p>文档编写过程和写一般的 markdown 文章差不多，有一些需要注意的地方或是技巧需要说明一下。</p>
<ol>
<li>
<p>站点布局默认情况下，即在不配置导航 (nav) 的情况下，会按照文件名，目录结构生成导航菜单</p>
</li>
<li>
<p>站点首页默认情况下，必须创建一个 <a href="http://index.md" target="_blank" rel="noopener">index.md</a> 作为站点首页。同时也支持 <a href="http://README.md" target="_blank" rel="noopener">README.md</a> 作为首页，会将期转化为 index.html。如果 <a href="http://index.md" target="_blank" rel="noopener">index.md</a> 和 <a href="http://README.md" target="_blank" rel="noopener">README.md</a> 同时存在，将忽略 <a href="http://README.md" target="_blank" rel="noopener">README.md</a></p>
</li>
<li>
<p>非 markdown 文件<br>
markdown 文件，即扩展名为 md 的文件，会被转化为 html。非 markdown 文件，会被原封拷贝，不做任何修改</p>
</li>
<li>
<p>内部链接如果需要引用另一个文件，只需要按照 markdown 链接的方式，连接到这个文件就可以了，例如 <code>[详情请参考](./detail.md)</code>。不要担心文件名，因为生成站点时会自动换成 html 文件路径</p>
</li>
</ol>
<h2 id="生成站点">生成站点</h2>
<p>编写好文档后，需要将其生成为站点目录，即编译成 html 文件，才能发布。</p>
<p>使用 mkdocs 非常方便，只需要在项目目录中，执行以下命令即可:</p>
<figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">mkdocs build</span><br></pre></td></tr></table></figure>
<p>完成后，就会生成一个 <code>site</code> 文件夹，其中就是生成好的站点文件</p>
<h2 id="发布">发布</h2>
<p>写好文档，需要发布才能让更多的人看到和使用。</p>
<p>这里介绍两种发布方式，可以根据实际情况选择。</p>
<h3 id="自主发布">自主发布</h3>
<p>上一节，说明了如何生成站点，那么只要将生成好的站点文件，部署到服务器上就可以。</p>
<p>然后配置 Web 服务器的虚拟目录，例如常用的 nginx</p>
<figure class="highlight nginx"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line"><span class="attribute">location</span> /docs/ &#123;</span><br><span class="line">    <span class="attribute">alias</span> /home/www/site/;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure>
<p>这样就可以通过 <code>www.yourhost.com/docs</code> 访问到文件了（假如你已经有了域名 <a href="http://yourhost.com" target="_blank" rel="noopener">yourhost.com</a> 并解析到了服务器上）。</p>
<p>如果是在公司内部的话，只要将站点文件夹拷贝到网络网络管理员指定的位置，就可以了。</p>
<blockquote>
<p>自主发布需要更多的资源和知识，不过更自由和保密</p>
</blockquote>
<h3 id="Read-the-Docs">Read the Docs</h3>
<p>如果自主发布比较麻烦，可以选择 <a href="https://readthedocs.org/" target="_blank" rel="noopener" title="Read the Docs">Read the Docs</a>。</p>
<p>它是一个专门为文档而生的 Web 服务，可以便捷地发布文档，只需要注册一个账号。</p>
<p>Read the Docs 提供公开和商业两种版本，商业版可以发布私有文档，否则只能发布公开的文档，可以根据实际情况做出选择。</p>
<p>Read the Docs 支持 mkdocs 创建的文档项目，即，意味着不需要对 mkdocs 项目进行生成站点操作，就可以发布，这样就方便多了。</p>
<p>只需要在发布前，创建一个 Read the Docs 配置文件 <code>.readthedocs.yml</code> 就可以了。</p>
<figure class="highlight yml"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment"># Required</span></span><br><span class="line"><span class="attr">version:</span> <span class="number">2</span></span><br><span class="line"></span><br><span class="line"><span class="attr">mkdocs:</span></span><br><span class="line">  <span class="attr">configuration:</span> <span class="string">mkdocs.yml</span></span><br><span class="line"></span><br><span class="line"><span class="comment"># Optionally set the version of Python and requirements required to build your docs</span></span><br><span class="line"><span class="attr">python:</span></span><br><span class="line">   <span class="attr">version:</span> <span class="number">3.7</span></span><br><span class="line">   <span class="attr">install:</span></span><br><span class="line">   <span class="bullet">-</span> <span class="attr">requirements:</span> <span class="string">docs/requirements.txt</span></span><br></pre></td></tr></table></figure>
<ul>
<li><code>mkdocs</code> 用于指定文档使用 mkdocs 编写</li>
<li><code>configuration</code> 指定 mkdocs 文档项目的配置文件</li>
<li><code>python</code> 为可选项，如果文档需要 python 运行环境的话可以配置，如不需要可以不配置</li>
</ul>
<p>更多配置请参考 <a href="https://docs.readthedocs.io/en/stable/config-file/v2.html" target="_blank" rel="noopener" title="Read the Docs 配置">Read the Docs 配置</a>。</p>
<p>然后将 mkdocs 项目用 github 做版本管理，这是因为 Read the Docs 目前只支持通过 github 导入文件。</p>
<p>最后在 Read the Docs 的 <code>Add Projcet</code> 中，选择 Github 中的对应库，按照说明操作即可。</p>
<p>如果顺利将会获得一个文档的访问网址。</p>
<h2 id="总结">总结</h2>
<p>大多数人讨厌编写文档，不仅是因为编写文档很枯燥，而且也是因为文档形式多样，后期制作成本很高，容易有畏难情绪。</p>
<p>利用 mkdocs 和 Read the Docs 可以让我们将注意力和精力集中在文档编写本身上，而解放了文档后期制作的成本投入，而且还能更方便的让更多的人浏览，让我们的价值更大的体现。</p>
<p>期望这篇文章，能在文档编写上给你帮助和启示，让自己的价值更大化，比心。</p>

    </div>

    
    
    

      <footer class="post-footer">
          <div class="post-tags">
              <a href="/tags/%E7%BC%96%E7%A8%8B/" rel="tag"># 编程</a>
              <a href="/tags/%E6%B8%B8%E6%88%8F/" rel="tag"># 游戏</a>
              <a href="/tags/Pygame/" rel="tag"># Pygame</a>
          </div>

        

			<div id="wechat_subscriber" style="display: block; padding: 10px 0; margin: 20px auto; width: 100%; text-align: center">
    <img id="wechat_subscriber_qcode" src="/images/wechat-qcode.png" alt="太阳雪 wechat" style="width: 200px; max-width: 100%;"/>
    <div>关注我，获得更多精彩内容</div>
</div>

        
		
    <div class="post-nav">
      <div class="post-nav-item">
    <a href="/2021-06-18-experience-class/" rel="prev" title="定投人生课堂 体验课">
      <i class="fa fa-chevron-left"></i> 定投人生课堂 体验课
    </a></div>
      <div class="post-nav-item">
    <a href="/2021-07-23-pygame/" rel="next" title="只需一招，Python 将系统秒变在线版！">
      只需一招，Python 将系统秒变在线版！ <i class="fa fa-chevron-right"></i>
    </a></div>
    </div>
      </footer>
    
  </article>
  
  
  



          </div>
          
    <div class="comments" id="valine-comments"></div>

<script>
  window.addEventListener('tabs:register', () => {
    let { activeClass } = CONFIG.comments;
    if (CONFIG.comments.storage) {
      activeClass = localStorage.getItem('comments_active') || activeClass;
    }
    if (activeClass) {
      let activeTab = document.querySelector(`a[href="#comment-${activeClass}"]`);
      if (activeTab) {
        activeTab.click();
      }
    }
  });
  if (CONFIG.comments.storage) {
    window.addEventListener('tabs:click', event => {
      if (!event.target.matches('.tabs-comment .tab-content .tab-pane')) return;
      let commentClass = event.target.classList[1];
      localStorage.setItem('comments_active', commentClass);
    });
  }
</script>

        </div>
          
  
  <div class="toggle sidebar-toggle">
    <span class="toggle-line toggle-line-first"></span>
    <span class="toggle-line toggle-line-middle"></span>
    <span class="toggle-line toggle-line-last"></span>
  </div>

  <aside class="sidebar">
    <div class="sidebar-inner">

      <ul class="sidebar-nav motion-element">
        <li class="sidebar-nav-toc">
          文章目录
        </li>
        <li class="sidebar-nav-overview">
          站点概览
        </li>
      </ul>

      <!--noindex-->
      <div class="post-toc-wrap sidebar-panel">
          <div class="post-toc motion-element"><ol class="nav"><li class="nav-item nav-level-2"><a class="nav-link" href="#文档框架"><span class="nav-number">1.</span> <span class="nav-text">文档框架</span></a></li><li class="nav-item nav-level-2"><a class="nav-link" href="#Mkdocs"><span class="nav-number">2.</span> <span class="nav-text">Mkdocs</span></a><ol class="nav-child"><li class="nav-item nav-level-3"><a class="nav-link" href="#环境搭建"><span class="nav-number">2.1.</span> <span class="nav-text">环境搭建</span></a></li><li class="nav-item nav-level-3"><a class="nav-link" href="#创建项目"><span class="nav-number">2.2.</span> <span class="nav-text">创建项目</span></a></li><li class="nav-item nav-level-3"><a class="nav-link" href="#文档预览"><span class="nav-number">2.3.</span> <span class="nav-text">文档预览</span></a></li></ol></li><li class="nav-item nav-level-2"><a class="nav-link" href="#编写文档"><span class="nav-number">3.</span> <span class="nav-text">编写文档</span></a><ol class="nav-child"><li class="nav-item nav-level-3"><a class="nav-link" href="#配置"><span class="nav-number">3.1.</span> <span class="nav-text">配置</span></a></li><li class="nav-item nav-level-3"><a class="nav-link" href="#一些约定"><span class="nav-number">3.2.</span> <span class="nav-text">一些约定</span></a></li></ol></li><li class="nav-item nav-level-2"><a class="nav-link" href="#生成站点"><span class="nav-number">4.</span> <span class="nav-text">生成站点</span></a></li><li class="nav-item nav-level-2"><a class="nav-link" href="#发布"><span class="nav-number">5.</span> <span class="nav-text">发布</span></a><ol class="nav-child"><li class="nav-item nav-level-3"><a class="nav-link" href="#自主发布"><span class="nav-number">5.1.</span> <span class="nav-text">自主发布</span></a></li><li class="nav-item nav-level-3"><a class="nav-link" href="#Read-the-Docs"><span class="nav-number">5.2.</span> <span class="nav-text">Read the Docs</span></a></li></ol></li><li class="nav-item nav-level-2"><a class="nav-link" href="#总结"><span class="nav-number">6.</span> <span class="nav-text">总结</span></a></li></ol></div>
      </div>
      <!--/noindex-->

      <div class="site-overview-wrap sidebar-panel">
        <div class="site-author motion-element" itemprop="author" itemscope itemtype="http://schema.org/Person">
    <img class="site-author-image" itemprop="image" alt="太阳雪"
      src="/images/avatar.png">
  <p class="site-author-name" itemprop="name">太阳雪</p>
  <div class="site-description" itemprop="description">总结 技术 思考 想法</div>
</div>
<div class="site-state-wrap motion-element">
  <nav class="site-state">
      <div class="site-state-item site-state-posts">
          <a href="/archives/">
        
          <span class="site-state-item-count">88</span>
          <span class="site-state-item-name">日志</span>
        </a>
      </div>
      <div class="site-state-item site-state-categories">
            <a href="/categories/">
          
        <span class="site-state-item-count">14</span>
        <span class="site-state-item-name">分类</span></a>
      </div>
      <div class="site-state-item site-state-tags">
            <a href="/tags/">
          
        <span class="site-state-item-count">47</span>
        <span class="site-state-item-name">标签</span></a>
      </div>
  </nav>
</div>



      </div>

    </div>
  </aside>
  <div id="sidebar-dimmer"></div>


      </div>
    </main>

    <footer class="footer">
      <div class="footer-inner">
        

        

<div class="copyright">
  
  &copy; 
  <span itemprop="copyrightYear">2022</span>
  <span class="with-love">
    <i class="fa fa-heart"></i>
  </span>
  <span class="author" itemprop="copyrightHolder">太阳雪</span>
</div>
  <div class="powered-by">由 <a href="https://hexo.io/" class="theme-link" rel="noopener" target="_blank">Hexo</a> & <a href="https://mist.theme-next.org/" class="theme-link" rel="noopener" target="_blank">NexT.Mist</a> 强力驱动
  </div>

        








      </div>
    </footer>
  </div>

  
  <script src="/lib/anime.min.js"></script>
  <script src="/lib/velocity/velocity.min.js"></script>
  <script src="/lib/velocity/velocity.ui.min.js"></script>

<script src="/js/utils.js"></script>

<script src="/js/motion.js"></script>


<script src="/js/schemes/muse.js"></script>


<script src="/js/next-boot.js"></script>




  
  <script>
    (function(){
      var canonicalURL, curProtocol;
      //Get the <link> tag
      var x=document.getElementsByTagName("link");
		//Find the last canonical URL
		if(x.length > 0){
			for (i=0;i<x.length;i++){
				if(x[i].rel.toLowerCase() == 'canonical' && x[i].href){
					canonicalURL=x[i].href;
				}
			}
		}
    //Get protocol
	    if (!canonicalURL){
	    	curProtocol = window.location.protocol.split(':')[0];
	    }
	    else{
	    	curProtocol = canonicalURL.split(':')[0];
	    }
      //Get current URL if the canonical URL does not exist
	    if (!canonicalURL) canonicalURL = window.location.href;
	    //Assign script content. Replace current URL with the canonical URL
      !function(){var e=/([http|https]:\/\/[a-zA-Z0-9\_\.]+\.baidu\.com)/gi,r=canonicalURL,t=document.referrer;if(!e.test(r)){var n=(String(curProtocol).toLowerCase() === 'https')?"https://sp0.baidu.com/9_Q4simg2RQJ8t7jm9iCKT-xh_/s.gif":"//api.share.baidu.com/s.gif";t?(n+="?r="+encodeURIComponent(document.referrer),r&&(n+="&l="+r)):r&&(n+="?l="+r);var i=new Image;i.src=n}}(window);})();
  </script>















  

  


<script>
NexT.utils.loadComments(document.querySelector('#valine-comments'), () => {
  NexT.utils.getScript('//unpkg.com/valine/dist/Valine.min.js', () => {
    var GUEST = ['nick', 'mail', 'link'];
    var guest = 'nick,mail';
    guest = guest.split(',').filter(item => {
      return GUEST.includes(item);
    });
    new Valine({
      el         : '#valine-comments',
      verify     : false,
      notify     : false,
      appId      : 'teRj7yeJj0xpfGKLJ5uFdbIu-gzGzoHsz',
      appKey     : '3uie0p1nxouCCnkjiXTEBeLd',
      placeholder: "您的关注是我的动力",
      avatar     : 'mm',
      meta       : guest,
      pageSize   : '10' || 10,
      visitor    : true,
      lang       : 'zh-cn' || 'zh-cn',
      path       : location.pathname,
      recordIP   : false,
      serverURLs : ''
    });
  }, window.Valine);
});
</script>

</body>
</html>
